The World of Computer Software/The World of Computer Software.iso/mbase1.zip/MBASE.DOC

Text File | 1992-12-16 | 34KB | 1,036 lines

                       Mbase5 v2.60
            The City, State, Zip Clipper Library

                Written by Thomas D. Stubbs
            All programs and documentation are
      Copyright 1992 by MAILbase.  All rights reserved.

                          MAILbase
                3074 Lancaster Dr NE Ste 222
                    Salem, OR 97305-1349
                       [phone]




                         - LICENSE -

MAILbase grants the purchaser a license to use this software
on one computer system.  The right to use this program can be
transfered to another user, on a different computer system, as
long as the program is never used on two different computer
systems at the same time.  If two systems use this program
at the same time it is a violation of this license.  MAILbase
authorizes you to make copies of this program as long as the
copies are only used for backing up the original diskettes in
the event they are destroyed. MAILbase grants you the right
to use, give away, or sell all programs that you write, and
compile with this product, however, due to an existing
licensing agreement with the United States Postal Service,
A LICENSING FEE IS REQUIRED if multiple copies of the City,
State, Zip datafile are to distributed by the purchaser of
this software.



                *** DISCLAIMER OF WARRANTY ***

THESE PROGRAMS ARE PROVIDED ON AN AS-IS BASIS. MAILBASE MAKES
NO WARRANTY, EXPRESS OR IMPLIED, AS TO PERFORMANCE, MERCHANT-
ABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL
MAILBASE BE HELD LIABLE FOR ANY DAMAGES, INCLUDING BUT NOT
LIMITED TO LOSS OF USE, LOST REVENUE, SPECIAL, CONSEQUENTIAL,
INDIRECT OR SIMILAR DAMAGES, EVEN IF MAILBASE OR AN AGENT OF
MAILBASE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
IN NO EVENT SHALL MAILBASE LIABILITY FOR ANY DAMAGES EVER
EXCEED THE PRICE PAID FOR THE SOFTWARE, REGARDLESS OF THE
FORM OF THE CLAIM.





Overview:

   The MAILBASE.CSZ file is an optimally compressed file that
contains all City, State, and Zip Codes currently recognized
by the United States Postal Service.  This data is cross-
referenced in several ways to allow a developer to create an
interactive enviroment that makes data entry faster and more
accurate.  The functions provided simplify the development
of this enviroment, since all file handling, indexing,
filtering, and searching is built in.  Additionally, the
MAILBASE.CSZ file stands alone.  There are no other files
used or created, making the application more transportable
since the MAILBASE.CSZ file is only about 800K (compare this
to using DBF's and NTX's which would require 5 to 10 times
as much disk space).

   The data contained in MAILBASE.CSZ is much more in depth
than merely the City, State, and Zip Codes.  Each data type,
is assigned a TYPE CODE which the developer can interpret
for further cross referencing.  The city names included not
only have the USPS recognized preferred names, but also
approved abbreviations and local community names comprising
over 80,000 city names.  The type codes for the city will
tell the delevoper if an alternate name is available or
preferred and if an abbreviation exists.  (All approved
city names longer than 13 characters have a corresponding
approved abbreviation).  States are categorized by US state,
territory, or Military PO.  Zip codes are identified as
general/residential, PO Boxes Only, Unique to a single
company or government office, or APO/FPO.

   The MAILBASE.CSZ file contains the most current
information available from the United States Postal
Service.  Updates are available the second month of
each quarter, (FEBRUARY, MAY, JULY, & NOVEMBER).




About City Types:

   There are currently 9 city types defined.  The numbers
used are spaced to allow room for future development with
little or no upgrade shock.  Frequently a Zip Code will
have more than one valid City Name.  In this library these
City Names are assigned a level of precedence.  The most
common city name for a given zip code is called the
'Dominant' city name.  This does not necessarily mean it
is more correct than the city name inputed.  However, if
the dominant name is used, the Post Office will still be
able to deliver it.  If a zip code has more than one city
name, this means that each city is valid for that zip.
The dominant is the city that uses most of that zip code.
Note that the city type is specific to a particular
city and zip combination.  It would not be correct to
assume that a type code for a city in one zip code would
be the same as that in the next zip code.  If the returned
city type is greater than 1, then that zip code will have
alternative names available.  In the case of the city type
equal to 6 or 7 there will be two alternative city names.
The alternate names are returned by using the CITYAKA()
function.

    type  1: Dominant City Name, no alternates available)
    type  2: Abbreviation of a Dominant, alternate will
             be the full city name.
    type  3: Dominant that has an abbreviation, alternate
             will be abbreviation.
    type  4: City name that has equal alternate (neither
             is more dominate than the other), alternate
             will be the other.
    type  5: Non-dominate city name, alternate will be
             the dominate city name.
    type  6: Abbreviation of a non-dominant (has 2
             alternates), alternate 1 will be the
             unabbreviation of the non-dominate,
             alternate 2 will be the dominate city name.
    type  7: Non-dominant that has an Abbreviation (has
             2 alternates), alternate 1 will be the
             abbreviation of the non-dominate,
             alternate 2 will be the dominate city name
    type 17: Abbreviation or a non-dominant, this is
             both an approved abbreviation as well as
             a locally known name.  Alternate will be
             the dominate city name.
    type 32: This is a locally known name, however it
             is not an approved USPS name.  You should
             use its alternate which will be the
             dominate city name.

Large cities will have numerous unapproved names (type 32).
One of the advantages about non-dominant or unapproved
names is that they help narrow down the exact zip code
for a dominate zip name.  For example Eola, Oregon is
an unapproved city name.  The correct city to use is
Salem, Oregon, however, Salem uses Zipcodes 97301-97314.
Eola is specifically 97304, therefor the proper
alternative would be Salem, OR 97304.




About State Types:

There are only 3 types of states currently defined.  The
most common are the 51 US states (includes DC).  There
are 3 abbreviation assigned to APO's and FPO's (AA, AE
and AP).  The other type are the US territories or
non-US states that have been assigned an abbreviation.
Appendix B lists all of the abbreviations currently
assigned by the USPS.

    type 1: US State
    type 2: US territory or non-US state
    type 3: APO/FPO's




About Zip Types:

There are 4 Zip types.  The most common are the general/
residential zip codes.  Additionally, some zip codes are
used for PO Boxes only.  If the street address is not
a PO Box but the zip code is identified as a PO Box only
then the wrong zip code is being used.  Some zip codes
are unique to large company, organization, or government
offices.  If a residential street address has one of
these zip codes, the wrong zip code is being used.
Lastly, there are several zip codes assigned to APO's
and FPO's (military overseas Post Offices).

    type 1: general/residential
    type 2: PO Box Only
    type 3: Unique
    type 4: APO/FPO's





               - DOCUMENTATION STANDARDS -


Required parameters are shown enclosed with <> and optional
parameters with [].

Parameters are usually descriptive and will always be shown
lowercase with the first character upper case, indicating
its data type (i.e. C-Character, L-logical, N-numeric, A-array).

Functions are usually displayed and referred to in upper case.
However if you are compiling with case sensitivity ON, you
should use them exactly as displayed in the Syntax and
Example (mixed case).



    CITY2ZIP()
    ──────────────────────────────────────────────────────────
    Syntax: City2Zip(<Ccity>,[Azip],[Actype],[Aztype],;
                     [Csfilter],[Lcfilter],[Nzfilter])


    Use:  To determine the existence of a city name and
          fill arrays for zipcode, city type code, and
          zip type code.


    Arguments:

        <Ccity>    is the city name character string to be
                   searched for.

        [Azip]     is the array to be filled with zip codes
                   valid for the city name (listed in
                   ascending order).

        [Actype]   is the array to be filled with city type
                   code corresponding to each zip.  (see
                   discussion on city types and table 1).

        [Aztype]   is the array to be filled with zip type
                   code corresponding to each zip.  (see
                   discussion on zip types and table 2).

        [Csfilter] is a USPS approved two letter state
                   abbreviation.  If included only those
                   zipcodes for this state will be found.

        [Lcfilter] is a logical to exclude zipcodes for
                   which the city is not a preferred name.
                   (set .T. to exclude).

        [Nzfilter] is a binary encoded numeric for the zip
                   types 1-4.  If specified, only those zips
                   of this type will be found. Default is
                   0 (see table 3)


    Return Value of the Function:  Numeric, the total number
        of elements meeting the search criteria regardless of
        array size.  Arrays will only be filled up to this
        value or the maximum declared array size.


    Error Determination:  If the return value is 0, the city
        name was not found.  Values less than 0 indicate an
        error.  Call MbaseErr() to determine nature of the
        error.


    Discussion:  This function is ideal for creating a pick
        list of zip codes or checking if an existing zip
        code and city combination is valid.  In operation,
        the first time a city is seeked, there will be a
        potentially noticable delay, depending upon the
        number of zip codes involved.  Because seeking a
        city name is the slowest operation in this library,
        the last city seeked remains in memory so repeated
        seeks of the same city will be much faster.  The
        filters will reduce the total number of zip codes
        returned.  There is no case sensitivity or trimming
        needed for the city and state parameters.
           It is also possible to determine the city
        state and zip for some universities, large
        businesses, and government agencies.  Several
        have been included among the list of cities and will
        usually return a city type of 32.  Given the
        returned zip you could then determine the
        proper city etc.  Try 'Readers Digest' for
        example.



           table 1:  City Types
         ┌─────┬───────────────────────────────────────┐
         │type │  meaning                              │
         ├─────┼───────────────────────────────────────┤
         │  1  │ Dominant City Name                    │
         │  2  │ Abbreviation of a Dominant            │
         │  3  │ Dominant that has an abbreviation     │
         │  4  │ City name that has equal alternate    │
         │  5  │ Non-dominate city name                │
         │  6  │ Abbreviation of a non-dominant        │
         │  7  │ Non-dominant that has an Abbreviation │
         │ 17  │ Abbreviation or a non-dominant        │
         │ 32  │ Unapproved name (should be replaced)  │
         └─────┴───────────────────────────────────────┘


           table 2:  Zip Types
         ┌─────┬──────────────────────┐
         │type │  meaning             │
         ├─────┼──────────────────────┤
         │  1  │ general/residential  │
         │  2  │ PO Box Only          │
         │  3  │ Unique               │
         │  4  │ APO/FPO's            │
         └─────┴──────────────────────┘


           table 3:  Zip filter values
         ┌──────┬─────────────────────────────┐
         │value │  action                     │
         ├──────┼─────────────────────────────┤
         │  1   │ include general/residential │
         │  2   │ include PO Box Only         │
         │  4   │ include Unique              │
         │  8   │ include APO/FPO's           │
         ├──────┴─────────────────────────────┤
         │ The sum of these values establish  │
         │ the Nzfilter.  Nzfilter=0 includes │
         │ all (same as Nzfilter=15).         │
         └────────────────────────────────────┘


    Examples:

        city="SALEM"
        state="OR"

        City2Zip(city)                        && returns 58
        City2Zip(city,"","","",state)         && returns 14
        City2Zip(city,"","","",state,.T.)     && returns 14
        City2Zip(city,"","","",state,,.T.,3)  && returns  9
        City2Zip(city,"","","",state,.T.,1)   && returns  6





    CITYAKA()
    ──────────────────────────────────────────────────────────
    Syntax:  CityAKA(<Ccity>,<Czip>,<Nindex>)

    Use:  To retrieve other acceptable names or abbreviations
          that the city with the given zip may also be known
          as.


    Arguments:

        <Ccity>    is the city name character string to be
                   searched for.

        <Czip>     is the zip code that must exist for the
                   given city to determine the AKA.

        <Nindex>   is the number of the AKA to return for
                   city/zips that have more than one AKA.
                   Currently this number is either 1 or 2.


    Return Value of the Function:  Character string.


    Error Determination:  Null string is returned if the Zip
        does not exist for this city, no AKA exists or
        <Nindex> is greater than the number of AKAs available.
        MbaseErr() will be 0 for any of these cases.
        MbaseErr() will be non zero in the event of an error.


    Discussion:  This function retrieves the alternate names
        for city and zip combinations that have a city type
        greater than 1.  For city types 32 you should call
        this function to get the correct city name.  All
        other alternatives are essentially optional.  For
        long city names (length > 13) an abbreviation will
        be available.  It is conceivable that your database
        structure could have city field length equal to 13
        since there will always be an abbreviation less than
        14 characters long.  This function will also convert
        the abbreviation back to the full city name.  In
        the case of non-dominant cities,  this function could
        also reveal other cities that may be near it, even
        if you choose not to use the dominant city name.


    Example:

        DECLARE ziparray[10],typearry[10]
        city="EOLA"
        state="OR"

        retval=City2Zip(city,ziparray,typearry,"",state)

           && returns a value of 1
           && typearry[1] = 32
           && should replace city with:

        repcity=CityAKA(city,ziparray[1],1)

           && returns SALEM



    CITYTYPE()
    ──────────────────────────────────────────────────────────
    Syntax:  CityType(<Ccity>,<Czip>)


    Use:  To determine the city type code for the given city
          and zip.


    Arguments:

        <Ccity>    is the city name character string to be
                   searched for.

        <Czip>     is the zip code that must exist for the
                   given city to determine type code.


    Return Value of the Function:  Numeric


    Error Determination:  Return value will be zero if
        the city does not exist or if the zip does not exist
        within that city.  A negative number is returned if
        an error occurs.  Use MbaseErr() to determine the
        cause of the error.


    Discussion:  This function gives a quick way to determine
        a city type without have to use the City2Zip() function
        and handling the arrays.  With this function the
        developer could take a given city and zip, then
        determine whether or not the city is valid, or has
        a possible alternate.


    Example:

        city= "EOLA"
        zip = "97304"

        retval=CityType(city,state)

        do case

           case retval=0
              ? "         *** error ***           "
              ? "this city does not exist or this "
              ? "zip code is invalid for this city"

           case retval=32
              ? "       *** warning ***
              ? "this city is not USPS approved"
              ? "it should be replaced with... "
              ? CityAKA(city,zip,1)

           case retval>1
              ? "       *** notice ***          "
              ? "alternative city names are also"
              ? "valid for this city & zip code "

        endcase




    CLOSEMBASE()
    ──────────────────────────────────────────────────────────
    Syntax:  CloseMbase()


    Use:  To close the datafile and free allocated memory.


    Arguments:  none


    Return Value of the Function:  none


    Error Determination:  N/A


    Discussion:  When the MAILBASE.CSZ file is opened one
    file handle is used and 1-2K of memory is allocated
    from the heap.  If you need to deallocate this memory,
    free up a file handle, or resolve some sharing
    problem this function is available.




    FILLSTATE()
    ──────────────────────────────────────────────────────────
    Syntax:  FillState(<Cstate>,[Nfilter])

    Use:  To fill an array with all current USPS approved
    state abbreviations.

    Arguments:

        <Cstate>  is a USPS approved two letter state
                  abbreviation.

        [Nfilter] is a binary encoded numeric for the
                  state types to return.  The default
                  is 7 (all types).   [see table 4]


    Return Value of the Function:  Numeric (Number of
        elements meeting the filter criteria regardless
        of declared array size).


    Error Determination:  A negative number is returned
        if an error occurs.  Use MbaseErr() to determine
        the cause of the error.


            table 4:
          ┌───────┬─────────────────────────┐
          │ value │   meaning               │
          ├───────┼─────────────────────────┤
          │   1   │ include US states       │
          │   2   │ include US territories  │
          │   4   │ include APO/FPO's       │
          ├───────┴─────────────────────────┤
          │ the sum of these values         │
          │ establishes the filter criteria │
          └─────────────────────────────────┘


    Discussion:  Because the potential exists that more
        states (most likely territories or Pacific Islands)
        will be assigned abbreviations in the future, it
        may be safer for a developer to use this function
        rather than hard coding the abbreviations.  Any
        changes will be contained within the updated
        MAILBASE.CSZ file, thus no recompile is needed.
        Plus it simply gives the developer an easy way
        of creating a pick list or table of states.




    ISSTATE()
    ──────────────────────────────────────────────────────────
    Syntax:  IsState(<Cstate>)


    Use:  To determine if a two character abbreviation is an
    approved USPS approved abbreviation for a US state.


    Arguments:

         <Cstate> is a USPS approved two letter state
                  abbreviation.


    Return Value of the Function:  logical


    Error Determination:  .F. is returned if either the input
        is not a valid state abbreviation or if an error
        occurs.  Use MbaseErr() to determine the if/what
        caused the error.


    Discussion:  Ideal function for a VALID function on
        a GET.  See example.


    Example:

        state="  "

        @ 10,30 SAY "Enter your state:" GET state VALID (IsState(state))
        READ





    MBASEERR()
    ──────────────────────────────────────────────────────────
    Syntax:  MbaseErr()


    Use:  To determine if and/or cause of an error created by
    the last executed Mbase function.


    Arguments:  none


    Return Value of the Function:  numeric


    Error Determination:  N/A


          table 5:  error values
        ┌─────┬──────────────────────────────────┐
        │value│   meaning                        │
        ├─────┼──────────────────────────────────┤
        │  1  │ Error opening MAILBASE.CSZ file  │
        │  2  │ Read error with MAILBASE.CSZ     │
        │  3  │ Memory allocation error          │
        └─────┴──────────────────────────────────┘





    OPENMBASE()
    ──────────────────────────────────────────────────────────
    Syntax:  OpenMbase([Cpath],[Lshared])


    Use:  To open the MAILBASE.CSZ file and allocate
          memory from the memory pool.


    Arguments:

        [Cpath]   path to the MAILBASE.CSZ file.  If not
                  specified, the default directory is
                  used.

        [Lshared] if .T. the MAILBASE.CSZ file will be
                  opened in shared mode.  You must have
                  SHARE installed to do this.  Default
                  is .F.


    Return Value of the Function: Numeric


    Error Determination:  Returns 0 if successful or
        error code if unsuccessful.


    Discussion:  This function allows the developer
        to modify the path or open the MAILBASE.CSZ
        file shared to suit the environment.
        However, the file name cannot be modified.
        Note: if you do not execute OpenMbase() prior
        to executing one of the other functions.
        OpenMbase() will be automatically executed
        with its defaults.

    Example:

        if OpenMbase("\MYDIR",.T.) # 0

           ? "ERROR OPENING MAILBASE.CSZ FILE"

        endif





    STATEABBR()
    ──────────────────────────────────────────────────────────
    Syntax:  StateAbbr(<Cstatename>)


    Use:  To determine the USPS approved abbreviation
    for a given state.


    Arguments:

         <Cstatename> Full name of a state.


    Return Value of the Function: Character


    Error Determination:  Returns Empty string if unsuccessful.
        Use MbaseErr() to determine cause of the error.


    Discussion:  If you are like me, some state abbreviations
        don't seem quite so obvious.  For example,
        Missouri-MO, Arizona-AZ, Alaska-AK.  It would be
        very easy to mistakenly use MI,AR, or AL, which would
        of course be valid abbreviations, but place you in
        the wrong state.  In some enviroments it may be
        safer to have the user type in the statename, or
        select it from a pick list, then use this function
        to insert the abbreviation.





    STATENAME()
    ──────────────────────────────────────────────────────────
    Syntax:  StateName(<Cstate>)


    Use:  To determine the Full State Name for a
    USPS approved abbreviation.


    Arguments:

         <Cstate> is a USPS approved two letter state
                  abbreviation.


    Return Value of the Function: Character


    Error Determination:  Returns Empty string unsuccessful.
        Use MbaseErr() to determine cause of the error.


    Discussion:  This could be a space saver for some
        database structures where you want the user to
        be very clear what state they are looking at.
        If you had to allow enough room in your database
        to handle the worst case; "Federated States of
        Micronesia", alot of space is wasted on "OHIO".
        Instead save "FM" or "OH" and call this function
        when you display it to the user.



    ZIP2CITY()
    ──────────────────────────────────────────────────────────
    Syntax:  Zip2City(<Czip>,<Acity>,[Aztype])

    Use:  To fill an array with the acceptable city names
          for a given zip code.

    Arguments:

        <Czip>     is the zip code to be searched for.

        <Acity>    is the array to be filled with possible
                   names for this Zip.

        [Aztype]   is an array to fill with zip type codes
                   corresponding to each city.


    Return Value of the Function:  Numeric, the total number
        of elements meeting the search criteria regardless of
        array size.  Arrays will only be filled up to this
        value or the maximum declared array size.


    Error Determination:  If the return value is 0, the zip
        code was not found.  Values less than 0 indicate an
        error.  Call MbaseErr() to determine nature of the
        error.


    Discussion:  This is the real time saver for data entry.
        Let the user enter the zip code first, then you can
        provide a pick list of cities.  Along with the
        Zip2State() function to fill in the state field.


    Example:

        ZIP=SPACE(5)

        DO WHILE .T.

          @ 10,32 SAY "Enter your Zip Code:"
          @ 11,38 GET ZIP
          READ

          DECLARE CITIES[30],ZTYPE[30]
          RET_VAL=Zip2City(ZIP,CITIES,ZTYPE)

          DO CASE
            CASE RET_VAL>0
              DISP_BOTTOM=IIF(RET_VAL>14,20,5+RET_VAL)
              @ 2,39 TO DISP_BOTTOM,69 DOUBLE
              CTY=ACHOICE(5,40,DISP_BOTTOM-1,68,CITIES,.T.)
              REPLACE CITY WITH CITIES[CTY]
              REPLACE STATE WITH Zip2State(ZIP)
              EXIT

            CASE RET_VAL=0
              @ 14,30 SAY "Invalid Zip, Please re-enter"

            CASE RET_VAL<0
              ? "INTERNAL ERROR"

          ENDCASE

        ENDDO


    ZIP2STATE
    ──────────────────────────────────────────────────────────
    Syntax:  Zip2State(<Czip>)

    Use:  To return the USPS approved two character
          state abbreviation for a given Zip Code.

    Arguments:

        <Czip>     is the zip code to be searched for.


    Return Value of the Function: Character


    Error Determination:  Null is returned if an error
        occurs.  This function will return a state regardless
        of whether or not that Zip code has currently been
        assigned by the USPS.


    Discussion:  Do not rely on this function to
        determine the validity of a zipcode.  Validity
        is only detected by Zip2City() returning a
        value greater than 0.  This function will always
        return a state regardless of whether or not that
        zip code has actually been assigned by the USPS.
        To conserve disk space in most cases the state
        is derived from the first 3 digits.  This function
        does of course handle the exceptions to this rule
        as well.




    ZIPTYPE
    ──────────────────────────────────────────────────────────
    Syntax:  ZipType(<Czip>)


    Use:  To determine the Zip type code for a given zip.


    Arguments:

        <Czip>     is the zip code to be searched for.


    Return Value of the Function:  Numeric


    Error Determination:  0 is returned if the Zip code
        does not exist, negative value indicates an error.
        Use MbaseErr() to determine the cause of the error.


    Discussion:  This is another way of getting the type
        of address expected for a given zip code.  If the
        street address is inconsistent with zip type then
        zip code used is wrong.


           table 2:  Zip Types
         ┌─────┬──────────────────────┐
         │type │  meaning             │
         ├─────┼──────────────────────┤
         │  1  │ general/residential  │
         │  2  │ PO Box Only          │
         │  3  │ Unique               │
         │  4  │ APO/FPO's            │
         └─────┴──────────────────────┘






                        APPENDIX A
                    SUMMARY OF TABLES



           table 1:  City Types
         ┌─────┬───────────────────────────────────────┐
         │type │  meaning                              │
         ├─────┼───────────────────────────────────────┤
         │  1  │ Dominant City Name                    │
         │  2  │ Abbreviation of a Dominant            │
         │  3  │ Dominant that has an abbreviation     │
         │  4  │ City name that has equal alternate    │
         │  5  │ Non-dominate city name                │
         │  6  │ Abbreviation of a non-dominant        │
         │  7  │ Non-dominant that has an Abbreviation │
         │ 17  │ Abbreviation or a non-dominant        │
         │ 32  │ Unapproved name (should be replaced)  │
         └─────┴───────────────────────────────────────┘


           table 2:  Zip Types
         ┌─────┬──────────────────────┐
         │type │  meaning             │
         ├─────┼──────────────────────┤
         │  1  │ general/residential  │
         │  2  │ PO Box Only          │
         │  3  │ Unique               │
         │  4  │ APO/FPO's            │
         └─────┴──────────────────────┘


           table 3:  Zip filter values
                     for Cty2Zip()
         ┌──────┬─────────────────────────────┐
         │value │  action                     │
         ├──────┼─────────────────────────────┤
         │  1   │ include general/residential │
         │  2   │ include PO Box Only         │
         │  4   │ include Unique              │
         │  8   │ include APO/FPO's           │
         ├──────┴─────────────────────────────┤
         │ The sum of these values establish  │
         │ the Nzfilter.  Nzfilter=0 includes │
         │ all (same as Nzfilter=15).         │
         └────────────────────────────────────┘


           table 4:  State filter values
                     for FillState()
         ┌───────┬─────────────────────────┐
         │ value │   meaning               │
         ├───────┼─────────────────────────┤
         │   1   │ include US states       │
         │   2   │ include US territories  │
         │   4   │ include APO/FPO's       │
         ├───────┴─────────────────────────┤
         │ the sum of these values         │
         │ establishes the filter criteria │
         └─────────────────────────────────┘


           table 5:  error values
                     for MbaseErr()
         ┌─────┬──────────────────────────────────┐
         │value│   meaning                        │
         ├─────┼──────────────────────────────────┤
         │  1  │ Error opening MAILBASE.CSZ file  │
         │  2  │ Read error with MAILBASE.CSZ     │
         │  3  │ Memory allocation error          │
         └─────┴──────────────────────────────────┘






                    APPENDIX B
            LIST OF STATES & ABBREVIATIONS


         AA - APO/FPO (MIAMI)
         AE - APO/FPO (NEW YORK)
         AP - FPO (SAN FRANCISCO)
         AK - ALASKA
         AL - ALABAMA
         AR - ARKANSAS
         AS - AMERICAN SAMOA
         AZ - ARIZONA
         CA - CALIFORNIA
         CO - COLORADO
         CT - CONNECTICUT
         DC - DISTRICT OF COLUMBIA
         DE - DELAWARE
         FL - FLORIDA
         FM - FEDERATED STATES OF MICRONESIA
         GA - GEORGIA
         GU - GUAM
         HI - HAWAII
         IA - INDIANA
         ID - IDAHO
         IL - ILLINOIS
         IN - INDIANA
         KS - KANSAS
         KY - KENTUCKY
         LA - LOUISIANA
         MA - MASSACHUSETTES
         MD - MARYLAND
         ME - MAINE
         MH - MARSHALL ISLANDS
         MI - MICHIGAN
         MN - MINNESOTA
         MO - MISSOURI
         MP - NORTHERN MARINIA ISLANDS
         MS - MISSISSIPPI
         MT - MONTANA
         NC - NORTH CAROLINA
         ND - NORTH DAKOTA
         NE - NEBRASKA
         NH - NEW HAMPSHIRE
         NJ - NEW JERSEY
         NM - NEW MEXICO
         NV - NEVADA
         NY - NEW YORK
         OH - OHIO
         OK - OKLAHOMA
         OR - OREGON
         PA - PENNSYLVANIA
         PR - PUERTO RICO
         PW - PALAU ISLANDS
         RI - RHODE ISLAND
         SC - SOUTH CAROLINA
         SD - SOUTH DAKOTA
         TN - TENNESSEE
         TX - TEXAS
         UT - UTAH
         VA - VIRGINIA
         VI - VIRGIN ISLANDS
         VT - VERMONT
         WA - WASHINGTON
         WI - WISCONSIN
         WV - WEST VIRGINIA
         WY - WYOMING